home *** CD-ROM | disk | FTP | other *** search
/ The Atari Compendium / The Atari Compendium (Toad Computers) (1994).iso / files / umich / utils / whati~gz.zoo / readme < prev    next >
Text File  |  1992-09-13  |  5KB  |  137 lines
  1. whatis, whatisin, apropos v2.0.1 92/9/13
  2. ----------------------------------------
  3.  
  4. Here is an implementation of whatis(1), whatisin(1), and apropos(1).
  5. These were all built with gcc 1.40 with MiNT libs at PL 19. It has been
  6. tested on TOS 1.2 running MiNT 0.94. It does not use any MiNT-specific
  7. functions so it should run under TOS alone (untested).
  8.  
  9. This should just about complete an online documentation system consisting
  10. of:
  11.  
  12.     nroff        text formatter (for manpages)
  13.     man        manual "front end"
  14.     manpager    file viewer
  15.     apropos        given keyword, find appropriate documentation
  16.     whatisin    find out what is in each section of the manual
  17.     whatis        get summary of what a command, etc. is
  18.  
  19. Note that the nroff I just posted last week (~92/9/11) to atari.archive
  20. supports the .tm macro and hence the .IX man macro is implemented. This
  21. is useful for creating index entries. You could, in theory, write a macro
  22. that would generate an whatis database entry each time a manpage was
  23. formatted. .tm writes to stderr while nroff otherwise writes to stdout.
  24.  
  25.  
  26. Manifest
  27. --------
  28.  
  29.     apropos.1z    compressed, formatted manpage (manpager format)
  30.     apropos.c    source
  31.     apropos.man    nroff source for manpage
  32.     apropos.ttp    executable
  33.     common.c    common source code for all programs
  34.     makefile    what u expect
  35.     mkwhatis.8z    compressed, formatted manpage (manpager format)
  36.     mkwhatis.c    source for tool to help build databases
  37.     mkwhatis.ma8    nroff source for manpage
  38.     mkwhatis.ttp    executable
  39.     whatis.1z    compressed, formatted manpage (manpager format)
  40.     whatis.5z    compressed, formatted manpage (manpager format)
  41.     whatis._1_    example databases (manual section 1)
  42.     whatis._2_       "        "     (manual section 2)
  43.     whatis._4_       "        "     (manual section 4)
  44.     whatis._5_       "        "     (manual section 5)
  45.     whatis._7_       "        "     (manual section 7)
  46.     whatis._8_       "        "     (manual section 8)
  47.     whatis.c    source
  48.     whatis.h    common header file
  49.     whatis.ma5    nroff source for manpage
  50.     whatis.man    nroff source for manpage
  51.     whatis.ttp    executable
  52.     whatisin.1z    compressed, formatted manpage (manpager format)
  53.     whatisin.___    data file for whatisin
  54.     whatisin.c    source
  55.     whatisin.man    nroff source for manpage
  56.     whatisin.ttp    executable
  57.  
  58.  
  59. Installation
  60. ------------
  61.  
  62. You will need to set an environment variable, MANPATH, to the directory
  63. which will contain the databases. This is the same environment variable
  64. used by man(1) (mine, at least). If you don't set it (and if you don't
  65. override with the -P switch on these commands), the default directory is
  66. d:\usr\man.
  67.  
  68. So put this in your shell's startup file:
  69.  
  70.     setenv MANPATH path
  71.  
  72. where path is the directory.
  73.  
  74. Then copy whatis._?_ and whatisin.___ files there.
  75.  
  76. Copy the executables to your bin directory. If you have one, you should
  77. probably copy mkwhatis.ttp to your /etc directory instead. It is really
  78. more of an administration command.
  79.  
  80.  
  81. Building whatis Databases
  82. -------------------------
  83.  
  84. I have included several of my own whatis databases here. They were all
  85. built using the mkwhatis program (also included) though there was some
  86. hand editing involved (i.e., to add keyword fields).
  87.  
  88. mkwhatis is given a list of file names which are manpage source files
  89. (i.e., nroff -man). It will spew out a pretty good attempt at formatting
  90. entries for the database. For details on the format of the database, see
  91. the documentation in whatis(5), mkwhatis(8), and mkwhatis.c.
  92.  
  93. I decided to diverge from unix (BSD) practice and include a separate file
  94. for each section of the manual. To see what the sections are, see the file
  95. whatisin.___ (which is the data file for whatisin).
  96.  
  97. Typically, you should be able to move to the directory(ies) containing
  98. your unformatted manpages and do:
  99.  
  100.     cd man1
  101.     mkwhatis *.man > whatis._1_
  102.     cd ../man2
  103.     mkwhatis *.man > whatis._2_
  104.     cd ../man3
  105.     mkwhatis *.man > whatis._3_
  106.     etc...
  107.  
  108. There is no command line option to rename the database file. If you want
  109. to do that you will have to recompile.
  110.  
  111. whatis, apropos, and whatisin recognize sections from this list:
  112.  
  113.     0    general info
  114.     1    commands
  115.     2    system calls
  116.     3    library functions
  117.     4    devices, hardware, drivers, etc.
  118.     5    file formats
  119.     6    games
  120.     7    misc
  121.     8    sys admin commands
  122.     9    unused
  123.     l    local
  124.     n    new
  125.     o    old
  126.  
  127. To change this list, change SECTIONS macro in whatis.h and change whatisin.___
  128. file. These sections are normal unix convention, but you can use them in any
  129. other way you want.
  130.  
  131.  
  132. Enjoy...
  133.  
  134. Bill Rosenkranz
  135. rosenkra@convex.com
  136.  
  137.